Wait. Why can it more than requested?

Apparently size=0 means "read all". Please document it.

This was just copied from the documentation for BufferedReader.peek(), but I agree that it could be written better. Changed now.

Wait. Why can it more than requested?

BufferedReader.peek() ignores the size argument and just returns whatever it has in its internal buffer.

I would prefer that BytesIO.peek() documents its behavior, rather than BufferedReader.peek() behavior.

Absolutely, it’s already changed.

(BTW, is there a policy on who clicks the "Resolve conversation" button?)

Would it be possible to implement it without touching the position? This code is not thread safe. I don't know if it's supposed to be thread-safe. Maybe add a private read method which has an argument to decide to move the position or not.

Same remark for C code.

Good point; I implemented this now so that the position is not changed. I factored out a peek_bytes function in the C version that does not advance the position.

It seems though that neither the C nor the Python version of BytesIO are supposed to be thread safe. (They don’t use locks as e.g. BufferedReader does.) So I would suggest making them so would be a task for a different PR.

Why not default to size=0 like BufferedReader?

Read through the comments. In general anything returning a bytes rather than a bytes-like memoryview is going to require allocating and copying potentially many bytes... If the copy is really concerning I'd lean returning a memoryview rather than a bytes which is a mandatory copy.

memoryview came up in this comment and the three following it: #30808 (comment)

I don’t know what the conclusion is given your comment. Should a memoryview be returned instead? Most important to me is compatibility with what BufferedReader.peek() returns.

I am not too concerned about the extra memory for a bytes object as long as the default is size=1.

👍 to not using memoryview / definitely a good rationale in that thread.

On 3.14.0 BufferedReader (intentionally limiting buffer size) gives:

Python 3.14.0 (v3.14.0:ebf955df7a8, Oct  7 2025, 08:20:14) [Clang 16.0.0 (clang-1600.0.26.6)] on darwin
Type "help", "copyright", "credits" or "license" for more information.

>>> br = open('README.rst', 'rb', buffering=30)
>>> def show_start_end(buf):
...     print(f'{len(buf)=}|{buf=}')
... 
>>> show_start_end(br.peek())
len(buf)=30|buf=b'This is Python version 3.15.0 '
>>> show_start_end(br.peek(0))
len(buf)=30|buf=b'This is Python version 3.15.0 '
>>> show_start_end(br.peek(1))
len(buf)=30|buf=b'This is Python version 3.15.0 '
>>> _ = br.read(len(br.peek()))
>>> show_start_end(br.peek())
len(buf)=30|buf=b'alpha 7\n======================'

Which doesn't match the behavior here or defaults. That in particular concerns me because it seems like people will build and test I/O stack pieces (ex. file parsing) expecting the .peek behavior of BytesIO then get something different when they read actual files/data...

Looking for more alternatives, the documentation page says (https://docs.python.org/3/library/io.html#io.BufferedReader.peek):

Return bytes from the stream without advancing the position. The number of bytes returned may be less or more than requested. If the underlying raw stream is non-blocking and the operation would block, returns empty bytes.

To me that leaves an intentional gap where we can always return less data than the total amount available. Peek gives no guarantees. That makes me wonder: Could we default to 0 and just always slice [:DEFAULT_BUFFER_SIZE]?

That would mean you always get DEFAULT_BUFFER_SIZE which matches default BufferedReader behavior unless there is less data available. If called in a loop yes that's a DEFAULT_BUFFER_SIZE repeated copy (BufferedIO also does that / the bytes requires a copy), but it's a lot less than "the whole buffer".

memoryview came up in this comment and the three following it: #30808 (comment)

I don’t know what the conclusion is given your comment. Should a memoryview be returned instead? Most important to me is compatibility with what BufferedReader.peek() returns.

I am not too concerned about the extra memory for a bytes object as long as the default is size=1.

👍 to not using memoryview / definitely a good rationale in that thread.

On 3.14.0 BufferedReader (intentionally limiting buffer size) gives:

Python 3.14.0 (v3.14.0:ebf955df7a8, Oct  7 2025, 08:20:14) [Clang 16.0.0 (clang-1600.0.26.6)] on darwin
Type "help", "copyright", "credits" or "license" for more information.

>>> br = open('README.rst', 'rb', buffering=30)
>>> def show_start_end(buf):
...     print(f'{len(buf)=}|{buf=}')
... 
>>> show_start_end(br.peek())
len(buf)=30|buf=b'This is Python version 3.15.0 '
>>> show_start_end(br.peek(0))
len(buf)=30|buf=b'This is Python version 3.15.0 '
>>> show_start_end(br.peek(1))
len(buf)=30|buf=b'This is Python version 3.15.0 '
>>> _ = br.read(len(br.peek()))
>>> show_start_end(br.peek())
len(buf)=30|buf=b'alpha 7\n======================'

Which doesn't match the behavior here or defaults. That in particular concerns me because it seems like people will build and test I/O stack pieces (ex. file parsing) expecting the .peek behavior of BytesIO then get something different when they read actual files/data...

Looking for more alternatives, the documentation page says (https://docs.python.org/3/library/io.html#io.BufferedReader.peek):

Return bytes from the stream without advancing the position. The number of bytes returned may be less or more than requested. If the underlying raw stream is non-blocking and the operation would block, returns empty bytes.

To me that leaves an intentional gap where we can always return less data than the total amount available. Peek gives no guarantees. That makes me wonder: Could we default to 0 and just always slice [:DEFAULT_BUFFER_SIZE]?

That would mean you always get DEFAULT_BUFFER_SIZE which matches default BufferedReader behavior unless there is less data available. If called in a loop yes that's a DEFAULT_BUFFER_SIZE repeated copy (BufferedIO also does that / the bytes requires a copy), but it's a lot less than "the whole buffer".

Need a bit more than this. These helpers define "how do we make the many threads race as much as possible" / help synchornize their start.

This needs to also get added to the self.check section below which sets "this is the set of operations we're going to have race".

So self.check([truncate] + [read] * 10, self.ioclass(b'0\n'*204800)) for example tests what happens if a bunch of truncate and read calls race with eachtoher.